

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Installation Instructions &mdash; Cogent Viewer 0.1 documentation</title>
    
    <link rel="stylesheet" href="_static/rtd.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Cogent Viewer 0.1 documentation" href="index.html" />
    <link rel="up" title="Working with the software" href="code.html" />
    <link rel="next" title="The Database and Model API" href="models.html" />
    <link rel="prev" title="Working with the software" href="code.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="models.html" title="The Database and Model API"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="code.html" title="Working with the software"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Cogent Viewer 0.1 documentation</a> &raquo;</li>
          <li><a href="code.html" accesskey="U">Working with the software</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="installation-instructions">
<h1>Installation Instructions<a class="headerlink" href="#installation-instructions" title="Permalink to this headline">¶</a></h1>
<p>These are the installation instructions for the Web Interface.  For instructions
for the Base Code see the <a class="reference external" href="https://code.google.com/p/cogent-house/">google code</a> site.</p>
<div class="section" id="getting-the-source">
<h2>Getting the Source<a class="headerlink" href="#getting-the-source" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference external" href="http://code.google.com/p/cogent-house/">Cogent-house (Base Code)</a></li>
<li><a class="reference external" href="https://launchpad.net/cogent-house">Cogent-Viewer (Web Interface)</a></li>
</ul>
</div>
<div class="section" id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
<p>There are some dependencies to install the web interface</p>
<ol class="arabic simple">
<li>python-dev</li>
<li>python-pip</li>
<li>python-virtualenv</li>
<li>libmysqlclient-dev</li>
</ol>
<p>Additionally, mysql-python currently require</p>
<p>In Ubuntu (or another debian based system) these can be installed using:</p>
<div class="highlight-python"><pre>$sudo apt-get install python-dev python-pip python-virtualenv libmysqlclient-dev bzr</pre>
</div>
</div>
<div class="section" id="installing-in-a-virtual-environment">
<h2>Installing in a virtual environment<a class="headerlink" href="#installing-in-a-virtual-environment" title="Permalink to this headline">¶</a></h2>
<p>To aid development, this code has been configured to use setuptools for
distribution.  This allows changes to the code to be tested using the <a class="reference external" href="http://peak.telecommunity.com/DevCenter/setuptools#develop-deploy-the-project-source-in-development-mode">develop</a>
function. Allowing changes to the code to be immediately reflected in the python
environment, rather than requiring a fresh #setup.py install call.</p>
<p>Additionally, I recommend developing in a <a class="reference external" href="http://pypi.python.org/pypi/virtualenv">virtual environment</a> this is the equivalent of a clean
python install, allowing any problems that may occur with missing packages /
different package versions to be seen.  This is a great advantage when
packaging, as installing from scratch allows testing of installation steps.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Using a virtualenv is not mandatory.  For example if you are installing on a
production server and are unlikely to make any changes to the code.  However,
for development its a extremely useful tool.</p>
</div>
<div class="section" id="setting-up-a-virtual-environment">
<h3>Setting up a virtual environment<a class="headerlink" href="#setting-up-a-virtual-environment" title="Permalink to this headline">¶</a></h3>
<p>To setup the virtual environment.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">These steps use <em>pip</em> to install packages.  However, feel free to use your favourite package manager (easy-install etc)</p>
</div>
<ol class="arabic">
<li><p class="first">Install virtualenv:</p>
<div class="highlight-python"><pre>$pip install virtualenv</pre>
</div>
</li>
<li><p class="first">Setup Virtual Environment.  Using the <em>&#8211;no-site-packages</em> flag means that
we get the equivalent of a clean python install:</p>
<div class="highlight-python"><pre>$virtualenv --no-site-packages testenv</pre>
</div>
</li>
</ol>
<p>To use the virtual environment activate it.  Missing this stage can be a common
source of problems, as the program tries to use packages that are not in the system wide library:</p>
<div class="highlight-python"><pre>$cd testenv
$source bin/activate
(testenv)$</pre>
</div>
<p>And to shut everything down afterwards, deactivate it:</p>
<div class="highlight-python"><pre>(testenv)$ deactivate
$</pre>
</div>
</div>
</div>
<div class="section" id="installing-the-application">
<h2>Installing the application<a class="headerlink" href="#installing-the-application" title="Permalink to this headline">¶</a></h2>
<div class="section" id="downloading-the-code">
<h3>Downloading the Code<a class="headerlink" href="#downloading-the-code" title="Permalink to this headline">¶</a></h3>
<p>Grab the latest version of the source from launchpad</p>
<p>For Stable:</p>
<div class="highlight-python"><pre>$bzr branch lp:cogent-house</pre>
</div>
<p>To install in <em>development</em> mode:</p>
<div class="highlight-python"><pre>(testenv)$ setup.py develop</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>There appears to be a bug in easy_install when installing numpy.
This means that the setup.py develop step may not work.
A simple work around is to install numpy with pip (which for some reason works)
then rerun the setup script:</p>
<div class="last highlight-python"><pre>$pip install numpy
$python setup.py develop</pre>
</div>
</div>
</div>
<div class="section" id="setting-up-the-database">
<h3>Setting Up the Database<a class="headerlink" href="#setting-up-the-database" title="Permalink to this headline">¶</a></h3>
<p>The database setup script can be called by running:</p>
<div class="highlight-python"><pre>$initialize_cogentviewer_db &lt;config&gt;.ini</pre>
</div>
</div>
<div class="section" id="installing-the-javascript-libraries">
<h3>Installing the Javascript Libraries<a class="headerlink" href="#installing-the-javascript-libraries" title="Permalink to this headline">¶</a></h3>
<p>Currently, the web interface uses a local version of the javascript libaries,
this avoids any problems when there is no internet connection available.</p>
<p>Unpack the <strong>jsLibs.tar.gz</strong> file in the same base directory as the webinterface:</p>
<div class="highlight-python"><pre>dan@einstein:~$tar -xvzf jsLibs.tar.qz
dan@einstein:~$ ls -l
total 38956
drwxr-xr-x 4 dan dan     4096 2012-06-15 14:53 cogent-house
drwxr-xr-x 5 dan dan     4096 2012-06-13 12:00 jslibs
-rw-r--r-- 1 dan dan  7456451 2012-06-15 14:57 jsLibs.tar.gz</pre>
</div>
</div>
</div>
<div class="section" id="running-a-local-copy-of-the-server">
<h2>Running a Local Copy of the Server<a class="headerlink" href="#running-a-local-copy-of-the-server" title="Permalink to this headline">¶</a></h2>
<p>Once the application is installed in development mode. It is possible to test the server</p>
<ol class="arabic">
<li><p class="first">Activate the virtual env:</p>
<div class="highlight-python"><pre>$cd testenv
$source bin/activate</pre>
</div>
</li>
<li><p class="first">Navigate to the cogent-viewer base directory:</p>
<div class="highlight-python"><pre>(testenv)$cd cogentviewer</pre>
</div>
</li>
<li><p class="first">Start the Paste server:</p>
<div class="highlight-python"><pre>(testenv)$pserve --reload development.ini</pre>
</div>
</li>
</ol>
<p>The web interface should now be available at <a class="reference external" href="127.0.0.1:6543">127.0.0.1:6543</a></p>
</div>
<div class="section" id="running-unit-tests">
<h2>Running Unit tests<a class="headerlink" href="#running-unit-tests" title="Permalink to this headline">¶</a></h2>
<p>The application also has a suite of unit tests.</p>
<p>Testing is performed using the <a class="reference external" href="http://readthedocs.org/docs/nose/en/latest/index.html">nose</a> test runner.</p>
<div class="section" id="setting-up-a-testing-database">
<h3>Setting up a testing database<a class="headerlink" href="#setting-up-a-testing-database" title="Permalink to this headline">¶</a></h3>
<p>Rather than use a live database, the Unit tests use a separate testing DB.</p>
<p>To set this up create a new schema <em>testStore</em> and user <em>test_user</em> with password <em>test_user</em></p>
<p>We also need to populate the database with its initial testing data the simplest
way to do this is to run an instance of the paste server using the test.ini
script:</p>
<div class="highlight-python"><pre>$initialize_cogentviewer_db test.ini</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to use an alternative database, it is possible to modify the
database string found in the <strong>test.ini</strong> setup file.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Unfortunately it is impossible to run the unit tests using a separate sqlite database
There have been locking issues as  parts of the code try to access the DB,
meaning that several tests fail.</p>
</div>
</div>
<div class="section" id="running-the-unit-tests">
<h3>Running the Unit tests<a class="headerlink" href="#running-the-unit-tests" title="Permalink to this headline">¶</a></h3>
<p>As the REST interface communicates with the server, we need to have an instance
of the web server running for the tests to complete.</p>
<ol class="arabic">
<li><p class="first">Start an Instance of the paste server running the test.ini script:</p>
<div class="highlight-python"><pre>(testenv)$pserve serve --reload test.ini</pre>
</div>
</li>
<li><p class="first">Run the Unit tests:</p>
<div class="highlight-python"><pre>(testenv)$nosetests</pre>
</div>
</li>
</ol>
</div>
</div>
<div class="section" id="running-under-apache-using-port-forwarding">
<h2>Running Under Apache using port forwarding<a class="headerlink" href="#running-under-apache-using-port-forwarding" title="Permalink to this headline">¶</a></h2>
<p>An alternative method to serve the web interface under apache,  setup a reverse proxy to forward requests to the paste serve</p>
<div class="section" id="setup-mod-proxy">
<h3>Setup Mod Proxy<a class="headerlink" href="#setup-mod-proxy" title="Permalink to this headline">¶</a></h3>
<p>We first need to enable the mod-proxy module on the apache server:</p>
<div class="highlight-python"><pre>$sudo a2enmod proxy</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you get an error loading the site, you may need to enable proxy_http</p>
</div>
<p>Then Modify the default site <em>/etc/apache2/sites-available/default</em>:</p>
<div class="highlight-python"><pre>ProxyRequests Off
ProxyPreserveHost On

&lt;Proxy *&gt;
    Order allow,deny
    Allow from all
&lt;/Proxy&gt;

ProxyPass /webInterface/ http://localhost:6543/
ProxyPassReverse /webInterface/ http://localhost:6543/</pre>
</div>
<p>Finally we need to make a modification to the paster .ini script used to serve the application,  add the following directing to the config file,  just before the <em>[server:main]</em> directive:</p>
<div class="highlight-python"><pre>filter-with = urlprefix

[filter:urlprefix]
use = egg:PasteDeploy#prefix
prefix = /webInterface</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This modification has been made in the <strong>proxy.ini</strong> config file</p>
</div>
</div>
</div>
<div class="section" id="building-the-documentation">
<h2>Building the Documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline">¶</a></h2>
<p>The Documents are built with Sphinx &lt;<a class="reference external" href="http://sphinx.pocoo.org/index.html">http://sphinx.pocoo.org/index.html</a>&gt;`_</p>
<p>Most of the information comes from docstrings in the code itself. Please keep these up to date.</p>
<p>To build the Docs it is as simple as:</p>
<div class="highlight-python"><pre>$cd docs
$make html</pre>
</div>
<p>Exporters are available for HTML and Latex (amongst others)</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Some Ubuntu versions of sphinx are old, and will generate an error
when building the graphs.  To avoid this install the latest version
of sphinx from PyPy:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="c">#sudo pip install --upgrade Sphinx</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="updating-the-database">
<span id="upgrading-the-database"></span><h2>Updating the Database<a class="headerlink" href="#updating-the-database" title="Permalink to this headline">¶</a></h2>
<p>The webinterface requires an upto date version of the database.  If the web
interface is installed on top of an pre-exisiting base server.  You will need to
update the database using the following steps.</p>
<ol class="arabic">
<li><p class="first">Get the and latest version of the base software, from <a class="reference external" href="http://code.google.com/p/cogent-house/">here</a></p>
</li>
<li><p class="first"><strong>Backup the Database</strong>:</p>
<div class="highlight-python"><pre>$mysqldump -u chuser -l -v ch &gt; chDump.sql</pre>
</div>
</li>
<li><p class="first">Install Alembic:</p>
<div class="highlight-python"><pre>$pip install alembic</pre>
</div>
</li>
<li><p class="first"><strong>Backup the Database</strong> (Included here incase you don&#8217;t feel it is important)</p>
</li>
<li><p class="first">Run the Alembic Upgrade Script:</p>
<div class="highlight-python"><pre>$alembic upgrade head</pre>
</div>
</li>
</ol>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Installation Instructions</a><ul>
<li><a class="reference internal" href="#getting-the-source">Getting the Source</a></li>
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li><a class="reference internal" href="#installing-in-a-virtual-environment">Installing in a virtual environment</a><ul>
<li><a class="reference internal" href="#setting-up-a-virtual-environment">Setting up a virtual environment</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-the-application">Installing the application</a><ul>
<li><a class="reference internal" href="#downloading-the-code">Downloading the Code</a></li>
<li><a class="reference internal" href="#setting-up-the-database">Setting Up the Database</a></li>
<li><a class="reference internal" href="#installing-the-javascript-libraries">Installing the Javascript Libraries</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-a-local-copy-of-the-server">Running a Local Copy of the Server</a></li>
<li><a class="reference internal" href="#running-unit-tests">Running Unit tests</a><ul>
<li><a class="reference internal" href="#setting-up-a-testing-database">Setting up a testing database</a></li>
<li><a class="reference internal" href="#running-the-unit-tests">Running the Unit tests</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-under-apache-using-port-forwarding">Running Under Apache using port forwarding</a><ul>
<li><a class="reference internal" href="#setup-mod-proxy">Setup Mod Proxy</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-the-documentation">Building the Documentation</a></li>
<li><a class="reference internal" href="#updating-the-database">Updating the Database</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="code.html"
                        title="previous chapter">Working with the software</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="models.html"
                        title="next chapter">The Database and Model API</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/install.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="models.html" title="The Database and Model API"
             >next</a> |</li>
        <li class="right" >
          <a href="code.html" title="Working with the software"
             >previous</a> |</li>
        <li><a href="index.html">Cogent Viewer 0.1 documentation</a> &raquo;</li>
          <li><a href="code.html" >Working with the software</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2011, Daniel Goldsmith.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
  </body>
</html>